home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / a_man / cat7 / poll.z / poll
Encoding:
Text File  |  2002-10-03  |  7.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ppppoooollllllll((((7777))))                                                                ppppoooollllllll((((7777))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      poll - device for high speed poll on file descriptors
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttrrrrooooppppttttssss....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppoooollllllll....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ddddeeeevvvvppppoooollllllll....hhhh>>>>
  15.  
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      /dev/poll is a device that allows users to efficiently monitor large
  19.      numbers of file descriptors.  /dev/poll works similarly to the _p_o_l_l
  20.      system call and to the Sun Solaris version of the device except as noted
  21.      below.  File descriptors to be polled are registered and scanned with the
  22.      _w_r_i_t_e and _i_o_c_t_l system calls respectively.
  23.  
  24.      Registration of file descriptors is done by writing an array of pollfd
  25.      structures to the /dev/poll device.  These structures are handled the
  26.      same as in _p_o_l_l and contain the following fields:
  27.  
  28.           int fd;             /* file descriptor  */
  29.           short events;       /* requested events */
  30.           short revents;      /* returned events  */
  31.  
  32.      Each passed pollfd is cached within the /dev/poll device.  If a previous
  33.      pollfd is found referencing the same file descriptor, their events fields
  34.      are combined.  Users wishing to maintain separate sets of registered
  35.      pollfd structures should open separate instances of the /dev/poll device.
  36.      The _w_r_i_t_e call returns the number of bytes written or -1 and an error
  37.      code.  Following a pollfd's registration, the device watches for the
  38.      events specified in the structure's events field to occur to the file
  39.      descriptor specified in the structure's fd field.
  40.  
  41.      Event notification is received through the _i_o_c_t_l system call using the
  42.      DDDDPPPP____PPPPOOOOLLLLLLLL command with a pointer to a dvpoll structure as its argument.
  43.      The dvpoll structure has the following fields:
  44.  
  45.           struct pollfd * dp_fds;       /* pollfd array     */
  46.           nfds_t dp_nfds;     /* Number of pollfds at dp_fds */
  47.           int dp_timeout;     /* Time-out in milliseconds   */
  48.  
  49.      dp_fds is an array to which up to dp_nfds pollfds with active events will
  50.      be copied by the device.  Each copied pollfd's revents field will include
  51.      those events in the events field that are active.  Each pollfd's fd field
  52.      will be set to the file descriptor that it was monitoring, and its events
  53.      field will be set to the events that it's watching for.  If no active
  54.      events are found, the call will block for the length of time in
  55.      dp_timeout.  If dp_timeout is 0 then the call will immediately return.
  56.      If dp_timeout is -1 then the call will block until a registered event
  57.      does become active.  If dp_timeout is greater than 0 then it will block
  58.      for that many milliseconds unless an event becomes active.  The _i_o_c_t_l
  59.      will return either the number of pollfds received, or -1 if an error
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ppppoooollllllll((((7777))))                                                                ppppoooollllllll((((7777))))
  71.  
  72.  
  73.  
  74.      occurred.
  75.  
  76.      A user can unregister pollfds from the device's poll set by adding the
  77.      PPPPOOOOLLLLLLLLRRRREEEEMMMMOOOOVVVVEEEE flag to the events field of a pollfd and writing it to the
  78.      device.  When a monitored file descriptor is closed, all /dev/poll
  79.      instances that had pollfds registered to monitor it will stop monitoring
  80.      the file.  The pollfds will remain cached in the /dev/poll device and can
  81.      be removed with the PPPPOOOOLLLLLLLLRRRREEEEMMMMOOOOVVVVEEEE flag as described above.  If a new file or
  82.      socket is opened with a file descriptor that is the same as a previously
  83.      closed file or socket that had a registered pollfd that is still cached
  84.      in a /dev/poll instance, the registered pollfd will not monitor the new
  85.      file or socket.  If a pollfd is written to one of these /dev/poll
  86.      instances to monitor this new file or socket, it will overwrite the no
  87.      longer used previous pollfd.
  88.  
  89.      Users may use the DDDDPPPP____RRRREEEEMMMMOOOOVVVVEEEE _i_o_c_t_l command on a /dev/poll instance to
  90.      direct the device to try to remove cached pollfds from the device
  91.      instance whenever the file descriptor that they are watching is closed.
  92.      The device instance will only attempt this while doing other work and it
  93.      may not always be successful.
  94.  
  95.      Users may use the DDDDPPPP____IIIISSSSPPPPOOOOLLLLLLLLEEEEDDDD _i_o_c_t_l command with a pollfd as the argument
  96.      to check if the file descriptor specified in the pollfds fd field is part
  97.      of the poll set for the /dev/poll instance queried.  The _i_o_c_t_l returns 1
  98.      if the file descriptor is part of the poll set, and returns the currently
  99.      polled events in the pollfd's events field.  The call returns 0 if the
  100.      file descriptor is not being polled and -1 if there was an error.
  101.  
  102.      When a program with an open instance of /dev/poll issues the _f_o_r_k system
  103.      call to create a child process, or _s_p_r_o_c to create a child with a non-
  104.      shared file descriptor table, any attempts by the child to _w_r_i_t_e or use
  105.      _i_o_c_t_l on the instance will fail with the EEEEAAAACCCCCCCCEEEESSSS error code.  It is
  106.      suggested that child processes close the instance and open a new one.
  107.      When the last open reference to an instance is closed, all cached pollfds
  108.      will be removed as well.
  109.  
  110. NNNNOOOOTTTTEEEESSSS
  111.      In the Sun Solaris version of /dev/poll, when a file descriptor is closed
  112.      that has /dev/poll pollfds monitoring it, and a new file is opened with
  113.      the same file descriptor, the pollfds will switch to monitor the new
  114.      file.  The IRIX version is different in that the pollfds will not switch
  115.      to monitor the new file descriptor.  They will remain dormant in their
  116.      /dev/poll instances until they are overwritten with new pollfds
  117.      referencing the file descriptor or they are removed with PPPPOOOOLLLLLLLLRRRREEEEMMMMOOOOVVVVEEEE.
  118.  
  119. HHHHIIIISSSSTTTTOOOORRRRYYYY
  120.      The /dev/poll device was added in IRIX 6.5.15.
  121.  
  122. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  123.      fork(2), ioctl(2), poll(2), sproc(2), write(2).
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ppppoooollllllll((((7777))))                                                                ppppoooollllllll((((7777))))
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.                                                                         PPPPaaaaggggeeee 3333
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.